home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 June: Reference Library / Dev.CD Jun 96 RL / Dev.CD Jun 96 RL.toast / What's New? / Development Kits / Apple Game Sprockets DR1 / Headers / NetSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-04-24  |  9.5 KB  |  384 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                              **
  3.  **     Module:        NetSprocket.h                                             **                        
  4.  **                                                                              **
  5.  **                                                                              **
  6.  **     Purpose:     Apple Game Sprockets Include file                         **            
  7.  **                                                                              **
  8.  **                                                                              **
  9.  **                                                                              **
  10.  **     Copyright (C) 1996 Apple Computer, Inc.  All rights reserved.         **
  11.  **                                                                              **
  12.  **                                                                              **
  13.  *****************************************************************************/
  14.  
  15. #ifndef __NETSPROCKET_H__
  16. #define __NETSPROCKET_H__
  17.  
  18. #ifndef SystemSevenOrLater
  19. #define SystemSevenOrLater    1
  20. #endif
  21.  
  22. #if PRAGMA_ALIGN_SUPPORTED
  23. #pragma options align=power
  24. #endif
  25.  
  26. #pragma enumsalwaysint on
  27.  
  28. #ifndef __TYPES__
  29. #include <Types.h>
  30. #endif
  31.  
  32. #ifndef __OPENTRANSPORT__
  33. #include <OpenTransport.h>
  34. #endif
  35.  
  36. #ifndef __OPENTPTINTERNET__
  37. #include <OpenTptInternet.h>
  38. #endif
  39.  
  40. #define kNSMaxPlayerNameLen        31
  41. #define kNSMaxGroupNameLen        31
  42. #define kNSMaxPasswordLen        31
  43. #define kNSMaxGameNameLen        31
  44.  
  45.  
  46. typedef    void        *TNetGameObject;
  47. typedef    SInt32        TGameID;
  48. typedef    SInt32        TPlayerID;
  49. typedef TPlayerID    TGroupID;
  50. typedef UInt32        TPlayerType;
  51. typedef SInt32        TNetFlags;
  52. typedef void        *TGameAddressRef;
  53. typedef UInt32        TSerialPort;
  54.  
  55. /* Topology types */
  56. typedef enum 
  57. {
  58.     kNSClientServer =     0x00000001
  59. } TTopology;
  60.  
  61.  
  62. /* Individual player info */
  63. typedef struct TPlayerInfo
  64. {
  65.     TPlayerID        id;
  66.     TPlayerType        type;
  67.     Str31            name;
  68.     UInt32            groupCount;
  69.     TGroupID        groups[kVariableLengthArray];
  70. } TPlayerInfo, *TPlayerInfoPtr;
  71.  
  72.     
  73. /* list of all players */
  74. typedef struct TPlayers
  75. {
  76.     UInt32            count;
  77.     TPlayerInfoPtr    playerInfo[kVariableLengthArray];
  78. } TPlayers, *TPlayersPtr;
  79.  
  80.  
  81. /* Individual group info */
  82. typedef struct TGroupInfo
  83. {
  84.     TGroupID    id;
  85.     UInt32        playerCount;
  86.     TPlayerID    players[kVariableLengthArray];
  87. } TGroupInfo, *TGroupInfoPtr;
  88.  
  89.  
  90. /* List of all groups */
  91. typedef struct TGroups
  92. {
  93.     UInt32            count;
  94.     TGroupInfoPtr    players[kVariableLengthArray];
  95. } TGroups, *TGroupsPtr;
  96.  
  97.  
  98. /* Game information */
  99. typedef struct TGameInfo
  100. {
  101.     UInt32        maxPlayers;
  102.     UInt32        currentPlayers;
  103.     UInt32        currentGroups;
  104.     TTopology    topology;
  105.     UInt32        reserved;
  106.     Str31        name;
  107.     Str31        password;
  108. } TGameInfo;
  109.     
  110.     
  111. /* Structure used for sending and receiving network messages */
  112. typedef struct TNetMessageHeader
  113. {
  114.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  115.     SInt32        what;        /* The kind of message (e.g. player joined) */
  116.     TPlayerID    from;        /* ID of the sender */
  117.     TPlayerID    to;            /* (player or group) id of the intended recipient */
  118.     UInt32        id;            /* Unique ID for this message & (from) player */
  119.     UInt32        when;        /* Timestamp for the message */
  120.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  121. } TNetMessageHeader;
  122.  
  123.  
  124. typedef struct TNSErrorMessage
  125. {
  126.     TNetMessageHeader    header;
  127.     OSStatus            error;
  128. } TNSErrorMessage;
  129.  
  130.  
  131. typedef struct TJoinRequestMessage
  132. {
  133.     TNetMessageHeader    header;
  134.     Str31                name;
  135.     Str31                password;
  136.     UInt32                type;
  137.     UInt32                customDataLen;
  138.     UInt8                customData[kVariableLengthArray];
  139. } TJoinRequestMessage;
  140.  
  141.  
  142. typedef struct TJoinApprovedMessage
  143. {
  144.     TNetMessageHeader    header;
  145. } TJoinApprovedMessage;
  146.  
  147.  
  148. typedef struct TJoinDeniedMessage
  149. {
  150.     TNetMessageHeader    header;
  151.     Str255                reason;
  152. } TJoinDeniedMessage;
  153.  
  154.  
  155. typedef struct TPlayerJoinedMessage
  156. {
  157.     TNetMessageHeader    header;
  158.     UInt32                playerCount;
  159.     TPlayerInfo            playerInfo;    
  160. } TPlayerJoinedMessage;
  161.  
  162.  
  163. typedef struct TPlayerLeftMessage
  164. {
  165.     TNetMessageHeader    header;
  166.     UInt32                playerCount;
  167.     TPlayerID            playerID;    
  168. } TPlayerLeftMessage;
  169.  
  170.  
  171.  
  172. /* Different kinds of messages */
  173. enum
  174. {
  175.     kJunk =             0x10000000,        /* will be sent (try once) when there is nothing else pending */
  176.     kNormal =             0x20000000,        /* will be sent immediately (try once) */
  177.     kRegistered =         0x30000000        /* will be sent immediately (guaranteed, in order) */
  178. };
  179.  
  180.  
  181. /* Options for message delivery */
  182. enum 
  183. {
  184.     kNSFailIfPipeFull = 0x00000001,
  185.     kSelfSend =         0x00000002,
  186.     kBlocking =         0x00000004
  187. };
  188.  
  189.  
  190. /* Options for Hosting Joining, and Deleting games */
  191. enum
  192. {
  193.     kNSNeedReliableTransport    =    0x00000001,
  194.     kNSForceTerminateGame         =     0x00000002
  195. };
  196.  
  197. /* T NetMessage "what" types */
  198. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  199. enum 
  200. {
  201.     kSystemMessage =         0x80000000,
  202.     kErrorMessage =         kSystemMessage | 0x7FFFFFFF,
  203.     kNSJoinRequest =         kSystemMessage | 0x00000001,
  204.     kNSJoinApproved =         kSystemMessage | 0x00000002,
  205.     kNSJoinDenied =         kSystemMessage | 0x00000003,
  206.     kNSPlayerJoined =         kSystemMessage | 0x00000004,
  207.     kNSPlayerLeft =         kSystemMessage | 0x00000005,
  208.     kNSHostChanged =         kSystemMessage | 0x00000006
  209. };
  210.  
  211.  
  212. /* Special TPlayerIDs  for sending messages */
  213. enum
  214. {
  215.     kNSAllPlayers =     0x00000000,
  216.     kNSServerOnly =        0xFFFFFFFF
  217. };
  218.     
  219.  
  220. /* Transport protocols returned by DoModalHostDialog */
  221. enum
  222. {
  223.     kAppleTalk =         0x00000001,
  224.     kTCPIP =             0x00000002,
  225.     kSerial =             0x00000004
  226. };
  227.  
  228.  
  229. /* Error codes (range: -4500 through -4001) */
  230. enum
  231. {
  232.     kNSNoError = 0,
  233.     initializationFailedErr = -4500,
  234.     alreadyInitializedErr,
  235.     topologyNotSupportedErr,
  236.     messageSizeTooBigErr,
  237.     bufferTooSmallErr,
  238.     receiveDataErr,
  239.     protocolNotAvailableErr,
  240.     invalidObjectErr,
  241.     invalidNetMessageErr,
  242.     invalidParameterErr,
  243.     OTNotPresentErr,
  244.     hostFailedErr,
  245.     notHostAddressErr,
  246.     memAllocationErr,
  247.     invalidProtocolErr,
  248.     alreadyAdvertisingErr,
  249.     noTypeSpecifiedErr,
  250.     notAdvertisingErr,
  251.     bogusDataErr,
  252.     tooMuchDataErr,
  253.     bogusAddressErr,
  254.     freeQExhaustedErr,
  255.     noSuchUserErr,
  256.     nameTakenErr,
  257.     portTakenErr,
  258.     gameInProgressErr,
  259.     featureNotImplementedErr,
  260.     nameRequiredErr,
  261.     invalidPlayerIDErr,
  262.     invalidGroupIDErr,
  263.     noPlayersErr,
  264.     noGroupsErr,
  265.     noHostVolunteersErr
  266. };
  267.  
  268.  
  269. #ifdef __cplusplus
  270. extern "C" {
  271. #endif
  272.  
  273. /************************  Initialization  ************************/
  274.  
  275. OSStatus InitializeNetSprocket(UInt32 inStandardMessageSize, UInt32 inBufferSize, UInt32 inQElements);
  276.  
  277.  
  278. /***********************  Human Interface  ************************/
  279.  
  280. TGameAddressRef DoModalJoinDialog(ConstStr31Param inGameType, ConstStr255Param inEntityListLabel, Str31 ioName, Str31 ioPassword);
  281.  
  282. UInt32    DoModalHostDialog(ConstStr255Param inHeading, InetPort *ioPort, Str31 ioGameName, Str31 ioPlayerName, Str31 ioPassword);
  283.  
  284.  
  285. /*********************  Hosting and Joining  **********************/
  286.  
  287. OSStatus NewGame(TNetGameObject *outGame, UInt32 inMaxPlayers, ConstStr31Param inGameName, ConstStr31Param inPassword, ConstStr31Param inPlayerName, TPlayerType inPlayerType, TTopology inTopology, TNetFlags inFlags);
  288.  
  289. OSStatus HostGameOnAppleTalk(TNetGameObject inGame, ConstStr31Param inGameType, UInt32 inMaxRTT);
  290.  
  291. OSStatus HostGameOnTCPIP(TNetGameObject inGame, InetPort *ioPort, UInt32 inMaxRTT);
  292.  
  293. OSStatus HostGameOnSerial(TNetGameObject inGame, UInt32 inPort, UInt32 inMinBaud);
  294.  
  295. OSStatus StopHostingAppleTalk(TNetGameObject inGame);
  296.  
  297. OSStatus StopHostingTCPIP(TNetGameObject inGame);
  298.  
  299. OSStatus StopHostingSerial(TNetGameObject inGame, UInt32 inPort);
  300.  
  301. OSStatus JoinGame(TNetGameObject *outGame, TGameAddressRef inAddress, ConstStr31Param inName, ConstStr31Param inPassword, TPlayerType inType, UInt32 inUserDataLen, void *inUserData, TNetFlags inFlags);
  302.  
  303. OSStatus DeleteGame(TNetGameObject inGame, TNetFlags inFlags);
  304.  
  305.  
  306. typedef Boolean (*TJoinRequestHandlerProcPtr)(TNetGameObject inGame, TJoinRequestMessage *inMessage, void* inContext);
  307.  
  308. OSStatus InstallJoinRequestHandler(TNetGameObject inGame, TJoinRequestHandlerProcPtr inHandler, void *inContext);
  309.  
  310.  
  311. /**************************  Messaging  **************************/
  312.  
  313. OSStatus SendNetMessage(TNetGameObject inGame, TNetMessageHeader *inMessage, TNetFlags inFlags);
  314.  
  315. TNetMessageHeader *GetNextNetMessage(TNetGameObject inGame);
  316.  
  317. void ReleaseNetMessage(TNetGameObject inGame, TNetMessageHeader *inMessage);
  318.  
  319. /* Async messaging support */
  320. typedef void (*TMessageHandlerProcPtr)(TNetGameObject inGame, TNetMessageHeader *inMessage,  void* inContext);
  321.  
  322. OSStatus InstallNetMessageHandler(TNetGameObject inGame, TMessageHandlerProcPtr inHandler, void *inContext);
  323.  
  324.  
  325. /*********************  Player Information  **********************/
  326.  
  327. TPlayerID GetMyPlayerID(TNetGameObject inGame);
  328.  
  329. OSStatus GetPlayerInfo(TNetGameObject inGame, TPlayerID inPlayerID, TPlayerInfoPtr *outInfo);
  330.  
  331. void ReleasePlayerInfo(TNetGameObject inGame, TPlayerInfoPtr inInfo);
  332.  
  333. OSStatus GetPlayers(TNetGameObject inGame, TPlayersPtr *outPlayers);
  334.  
  335. void ReleasePlayers(TNetGameObject inGame, TPlayersPtr inPlayers);
  336.  
  337.  
  338. /*********************  Group Management  **********************/
  339.  
  340. OSStatus CreateGroup(TNetGameObject inGame, TGroupID *outGroupID);
  341.  
  342. OSStatus DeleteGroup(TNetGameObject inGame, TGroupID inGroupID);
  343.  
  344. OSStatus AddPlayerToGroup(TNetGameObject inGame, TGroupID inGroupID, TPlayerID inPlayerID);
  345.  
  346. OSStatus RemovePlayerFromGroup(TNetGameObject inGame, TGroupID inGroupID, TPlayerID inPlayerID);
  347.  
  348. OSStatus GetGroupInfo(TNetGameObject inGame, TGroupID inGroupID, TGroupInfoPtr *outInfo);
  349.  
  350. void ReleaseGroupInfo(TNetGameObject inGame, TGroupInfoPtr inInfo);
  351.  
  352. OSStatus GetGroups(TNetGameObject inGame, TGroupsPtr *outGroups);
  353.  
  354. void ReleaseGroups(TNetGameObject inGame, TGroupsPtr inGroups);
  355.  
  356.  
  357. /**************************  Utilities  ***************************/
  358.  
  359. void ClearNetMessageHeader(TNetMessageHeader *inMessage);
  360.  
  361. UInt32 GetCurrentTimeStamp(TNetGameObject inGame);
  362.  
  363. UInt32 GetRoundTripTime(TNetGameObject inGame, TPlayerID inPlayer, UInt32 inTimeout); 
  364.  
  365. TGameAddressRef    OTAddressToGameAddressRef(OTAddress *inAddress);
  366.  
  367. OTAddress *GameAddressRefToOTAddress(TGameAddressRef inAddress);
  368.  
  369. void ReleaseGameAddressRef(TGameAddressRef inAddress);
  370.  
  371.  
  372.  
  373. #ifdef __cplusplus
  374. }
  375. #endif
  376.  
  377.  
  378. #if PRAGMA_ALIGN_SUPPORTED
  379. #pragma options align=reset
  380. #endif
  381.  
  382. #pragma enumsalwaysint reset
  383.  
  384. #endif